<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Aggregations | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="prev" href="sql-limitations.html" title="SQL Limitations">
<link rel="next" href="search-aggregations-metrics.html" title="Metrics Aggregations">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-node">Aggregations</span>
</div>
<div class="navheader">
<span class="prev">
<a href="sql-limitations.html">« SQL Limitations</a>
</span>
<span class="next">
<a href="search-aggregations-metrics.html">Metrics Aggregations »</a>
</span>
</div>
<div class="part">
<div class="titlepage"><div><div>
<h1 class="title">
<a id="search-aggregations"></a>Aggregations<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/aggregations.asciidoc">edit</a>
</h1>
</div></div></div>
<div class="openblock partintro">
<div class="content">
<p>The aggregations framework helps provide aggregated data based on a search query. It is based on simple building blocks
called aggregations, that can be composed in order to build complex summaries of the data.</p>
<p>An aggregation can be seen as a <em>unit-of-work</em> that builds analytic information over a set of documents. The context of
the execution defines what this document set is (e.g. a top-level aggregation executes within the context of the executed
query/filters of the search request).</p>
<p>There are many different types of aggregations, each with its own purpose and output. To better understand these types,
it is often easier to break them into four main families:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<a class="xref" href="search-aggregations-bucket.html" title="Bucket Aggregations"><em>Bucketing</em></a>
</span>
</dt>
<dd>
A family of aggregations that build buckets, where each bucket is associated with a <em>key</em> and a document
criterion. When the aggregation is executed, all the buckets criteria are evaluated on every document in
the context and when a criterion matches, the document is considered to "fall in" the relevant bucket.
By the end of the aggregation process, we’ll end up with a list of buckets - each one with a set of
documents that "belong" to it.
</dd>
<dt>
<span class="term">
<a class="xref" href="search-aggregations-metrics.html" title="Metrics Aggregations"><em>Metric</em></a>
</span>
</dt>
<dd>
Aggregations that keep track and compute metrics over a set of documents.
</dd>
<dt>
<span class="term">
<a class="xref" href="search-aggregations-matrix.html" title="Matrix Aggregations"><em>Matrix</em></a>
</span>
</dt>
<dd>
A family of aggregations that operate on multiple fields and produce a matrix result based on the
values extracted from the requested document fields. Unlike metric and bucket aggregations, this
aggregation family does not yet support scripting.
</dd>
<dt>
<span class="term">
<a class="xref" href="search-aggregations-pipeline.html" title="Pipeline Aggregations"><em>Pipeline</em></a>
</span>
</dt>
<dd>
Aggregations that aggregate the output of other aggregations and their associated metrics
</dd>
</dl>
</div>
<p>The interesting part comes next. Since each bucket effectively defines a document set (all documents belonging to
the bucket), one can potentially associate aggregations on the bucket level, and those will execute within the context
of that bucket. This is where the real power of aggregations kicks in: <span class="strong strong"><strong>aggregations can be nested!</strong></span></p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Bucketing aggregations can have sub-aggregations (bucketing or metric). The sub-aggregations will be computed for
		the buckets which their parent aggregation generates. There is no hard limit on the level/depth of nested
		aggregations (one can nest an aggregation under a "parent" aggregation, which is itself a sub-aggregation of
		another higher-level aggregation).</p>
</div>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Aggregations operate on the <code class="literal">double</code> representation of
        the data. As a consequence, the result may be approximate when running on longs
        whose absolute value is greater than <code class="literal">2^53</code>.</p>
</div>
</div>
<h2>
<a id="_structuring_aggregations"></a>Structuring Aggregations<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/aggregations.asciidoc">edit</a>
</h2>
<p>The following snippet captures the basic structure of aggregations:</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">"aggregations" : {
    "&lt;aggregation_name&gt;" : {
        "&lt;aggregation_type&gt;" : {
            &lt;aggregation_body&gt;
        }
        [,"meta" : {  [&lt;meta_data_body&gt;] } ]?
        [,"aggregations" : { [&lt;sub_aggregation&gt;]+ } ]?
    }
    [,"&lt;aggregation_name_2&gt;" : { ... } ]*
}</pre>
</div>
<p>The <code class="literal">aggregations</code> object (the key <code class="literal">aggs</code> can also be used) in the JSON holds the aggregations to be computed. Each aggregation
is associated with a logical name that the user defines (e.g. if the aggregation computes the average price, then it would
make sense to name it <code class="literal">avg_price</code>). These logical names will also be used to uniquely identify the aggregations in the
response. Each aggregation has a specific type (<code class="literal">&lt;aggregation_type&gt;</code> in the above snippet) and is typically the first
key within the named aggregation body. Each type of aggregation defines its own body, depending on the nature of the
aggregation (e.g. an <code class="literal">avg</code> aggregation on a specific field will define the field on which the average will be calculated).
At the same level of the aggregation type definition, one can optionally define a set of additional aggregations,
though this only makes sense if the aggregation you defined is of a bucketing nature. In this scenario, the
sub-aggregations you define on the bucketing aggregation level will be computed for all the buckets built by the
bucketing aggregation. For example, if you define a set of aggregations under the <code class="literal">range</code> aggregation, the
sub-aggregations will be computed for the range buckets that are defined.</p>
<h3>
<a id="_values_source"></a>Values Source<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/aggregations.asciidoc">edit</a>
</h3>
<p>Some aggregations work on values extracted from the aggregated documents. Typically, the values will be extracted from
a specific document field which is set using the <code class="literal">field</code> key for the aggregations. It is also possible to define a
<a class="xref" href="modules-scripting.html" title="Scripting"><code class="literal">script</code></a> which will generate the values (per document).</p>
<p>When both <code class="literal">field</code> and <code class="literal">script</code> settings are configured for the aggregation, the script will be treated as a
<code class="literal">value script</code>.  While normal scripts are evaluated on a document level (i.e. the script has access to all the data
associated with the document), value scripts are evaluated on the <span class="strong strong"><strong>value</strong></span> level. In this mode, the values are extracted
from the configured <code class="literal">field</code> and the <code class="literal">script</code> is used to apply a "transformation" over these value/s.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<a id="aggs-script-note"></a>
<p>When working with scripts, the <code class="literal">lang</code> and <code class="literal">params</code> settings can also be defined. The former defines the scripting
language which is used (assuming the proper language is available in Elasticsearch, either by default or as a plugin). The latter
enables defining all the "dynamic" expressions in the script as parameters, which enables the script to keep itself static
between calls (this will ensure the use of the cached compiled scripts in Elasticsearch).</p>
</div>
</div>
<p>Elasticsearch uses the type of the field in the mapping in order to figure out
how to run the aggregation and format the response. However there are two cases
in which Elasticsearch cannot figure out this information: unmapped fields (for
instance in the case of a search request across multiple indices, and only some
of them have a mapping for the field) and pure scripts. For those cases, it is
possible to give Elasticsearch a hint using the <code class="literal">value_type</code> option, which
accepts the following values: <code class="literal">string</code>, <code class="literal">long</code> (works for all integer types),
<code class="literal">double</code> (works for all decimal types like <code class="literal">float</code> or <code class="literal">scaled_float</code>), <code class="literal">date</code>,
<code class="literal">ip</code> and <code class="literal">boolean</code>.</p>
</div>
</div>









</div>
<div class="navfooter">
<span class="prev">
<a href="sql-limitations.html">« SQL Limitations</a>
</span>
<span class="next">
<a href="search-aggregations-metrics.html">Metrics Aggregations »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
